<!--

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

-->
<html>
<body>
<h1>Start with <code>DBI</code> and <code>Handle</code></h1>

<p>
    The main entry point to functionality is the <code>DBI</code> class. This class
    provides access to <code>Handle</code> instances, which are the primary means of
    interacting with database connections.
</p>

<p>
    The <code>Handle</code> is, generally, used to wrap a JDBC <code>Connection</code>
    instance. This connection will be used for all database operations by the handle,
    and will be closed when the handle is closed.
</p>

<h1>Idioms and Practices</h1>

<p>
    JDBI tries to use common Java practices, and standard interfaces as much as possible.
    This means that results are returned as <code>java.util.List</code> and <code>
    java.util.Iterator</code> instances, that working with JavaBeans (tm) is favored, etc.
</p>

<h3>Named Parameters</h3>

<p>
    You can use named parameters in SQL executed through JDBI. That means that statements
    such as <code>select id, name from profiles where age > :age</code> is valid. When
    executed it will be transformed to the traditional form,
    <code>select id, name from profiles where age > ?</code>. When binding arguments to
    a statement you may bind them either positionally or via the name, <code>age</code>
    in the example here. You may also mix positional and named argument binding and it
    should do the right thing.
</p>

<h3>Externalized SQL</h3>

<p>
    JDBI supports externalizing SQL via named queries. The default named query resolver
    looks for files on the classpath. The exact lookup rules for this locator can be
    found on the javadocs for <code>ClasspathStatementLocator</code>, but the gist is
    that you can do things like <code>handle.createQuery("queries/profile-by-id");</code> to
    fetch the SQL from the file <code>queries/profile-by-id.sql</code>. The locator
    can be replaced to find named statements by other means, and can be cached if desired.
</p>

<h1>Version Numbering</h1>

<p>
    JDBI uses the Apache APR versioning guidelines.
</p>

<h1>Caveats and Random Bits</h1>

<p>
    Most SQL in JDBI uses prepared statements. Non-prepared batch operations and scripts are
    the only places where regular statements are used. Prepared Statements are cached for the
    duration of an open handle, and will be reused on that handle. They are not cached on the
    <code>Connection</code>, but rather on the actual <code>Handle</code>, so if connection
    pooling is in use and you want to cache prepared statements between handle instances on
    the same connection you should do this at the data source level.
</p>

<p>
    The unit system tests are most often run against Apache Derby. If you encounter any issue
    against a different database, please consider running the tests against that database.
    Please <a href="mailto:dev@jdbi.codehaus.org">contact the dev mailing list</a> about these,
    or for help running the tests in a given environment. Thank you!
</p>

<h1>Design Principles</h1>
<ol>
    <li>Do the right thing for clients</li>
    <li>Do the right thing for extenders</li>
    <li>No configuration required</li>
    <li>Optimize the common cases</li>
</ol>
</body>
</html>